﻿<html>
<head><title>NRefactory - XML Documentation</title></head>
<body>
<h1>NRefactory - XML Documentation</h1>
<h2>Providing documentation for the type system</h2>
<p>
	When using CecilLoader, set the <code>CecilLoader.DocumentationProvider</code>
	property to provide documentation for the loaded assemblies.
	The <code>XmlDocumentationProvider</code> class is an <code>IDocumentationProvider</code> implementation
	that can be used to read documentation from an external .xml file in the format generated by
	Microsoft's C# compiler.
</p>
<p>
	When parsing C# code, the <code>TypeSystemConvertVisitor</code> will load the documentation
	from the XML comments by default. (this can be disabled using the <code>SkipXmlDocumentation</code> property).
</p>
<p>
	Internally, the type system does not store XML documentation - instead, the documentation is
	requested from the provider whenever the <code>IEntity.Documentation</code>
	property is accessed.<br/>
	For this purpose, the type system casts the parsed file to <code>IUnresolvedDocumentationProvider</code>
	and tries to get the documentation.
	This way, the <code>CSharpUnresolvedFile</code> can provide the documentation from the XML comments.<br/>
	If this fails, the type system casts the unresolved assembly/project content to <code>IDocumentationProvider</code>.
	This is the way the request for documentation gets to the <code>CecilLoader</code>,
	which in turn forwards it to the user-provided <code>IDocumentationProvider</code>.
</p>
<h2>cref</h2>
<p>
	The syntax taken by the <code>cref</code> attribute depends on the documentation source.
	For example, C# XML comments may use "<code>List{T}</code> if the appropriate <code>using</code> exists,
	but .xml documentation files have to use the full ID string <code>T:System.Collections.Generics.List`1</code>.
</p>
<p>
	For this reason, the <code>IEntity.Documentation</code> property returns a <code>DocumentationComment</code>
	object that provides not only the XML text, but also a method that can be used to resolve <code>cref</code>
	attributes.
</p>
<p>
	Internally, the .xml file support uses the <code>IDStringProvider</code>;
	whereas C# has its own small <code>CSharpCrefParser</code>.
</p>
<h2>XmlDocumentationProvider implementation notes</h2>
<p>
	The <code>XmlDocumentationProvider</code> is designed to load large amounts
	of documentation while using up only little memory.
</p>
<p>
	When a new <code>XmlDocumentationProvider</code> is created, it will read the .xml file and
	create a small in-memory index (using only 8 bytes per member).
	When documentation is requested from the provider, it uses this index to find the correct
	position in the .xml file, and parses only the interesting document fragment, not the whole file.
</p>
<p>
	The <code>XmlDocumentationProvider</code> is serializable and will be included when serializing a Cecil-loaded
	<code>IUnresolvedAssembly</code>. This way, an IDE like SharpDevelop can completely avoid parsing
	the .xml documentation file when the user opens a solution (except for the first time).
</p>
</body>
</html>
